A queue based file download manager for downloading files from the Internet using ftp, http, and Hotline protocols.
INDEX
1. Introduction / Description
1.1 What is it - Description
1.2 Why is it - Benefits
1.3 Why the name Monica
1.4 New Things on Version 2.2
1.5 Future Possibilities
2. Installation
2.1 Requirements
2.2 Software Installation
2.3 Quick Start
3. Commands and Settings
3.1 What are all these buttons
3.2 The Queue Display
3.3 Status Information
3.4 Download sub-windows
3.5 Preferences
3.6 File Name Ranges
3.7 Proxy Servers
4. Helper Applications
5. Monica and other Programs
5.1 Monica and Hotline
5.2 Monica and Applescript
5.3 Monica and PPP
6. Problems / Funnies
6.1 Known Problems
6.2 Virtual Memory Problems
6.3 Other Problems
6.4 Funnies
7. Distribution, Registration & Price
7.1 Distribution
7.2 Registering Monica
7.3 Price
8 Conditions of Use and Copyright
8.1 Legal conditions of Use
8.2 Copyright
9. Other Issues
9.1 Some Other Things
9.2 Note on Apple Data Detectors and Contextual Menus
10. Acknowledgements
10.1 Acknowledgements
10.2 Testers and Translators
11. Contacts, Queries and Suggestions
11.1 Contact Details
Appendix 1
Some HTTP Return/Error Codes
1. INTRODUCTION
1.1 What is it?
A queue based file download manager for downloading files from the Internet using ftp, http, and Hotline protocols.
MONICA achieves exceptional download throughput by utilising queue technology, optimised processing of Internet protocols, and by extensive use of transfer resumption techniques.
MONICA is shareware. The trial version allows you to download 50 files, after which you are required to register the program. ( See section 7. Distribution, Registration & Payment ).
1.2 Why is it?
Don't you hate it when :
• you have a lot of files to download and you have to sit in front of your browser waiting to be able to start the next one?
• you are downloading from a slow server and your browser deviously aborts your download leaving it incomplete?
• you cannot log onto an ftp server because it has reached its maximum number of logins?
Do you want:
• your downloads to automatically retry if the server connection is dropped?
• to restart downloads without losing what you have already got?
If you answered yes to any of these questions then MONICA is for you.
MONICA allows you to easily set up a download queue by 'dragging and dropping' or 'cutting and pasting' file URLs. Once you have placed some files in the queue you may manually start each download at a time convenient to you, or allow MONICA to start downloading automatically. In automatic mode, once a file is received MONICA will start the next one, allowing up to four simultaneous downloads. If the server times you out or if the download is incomplete then MONICA will restart the download and do her best to resume from where the download left off, while you can go off to more pleasant occupations.
1.3 Why the name MONICA?
Because I once had a cat called Monica that always would bring me things - dead mice, birds. lizards etc. This program should bring things to you, hopefully more pleasant things.
1.4 New things in Version 2.2
• Fixed Creator code
• Improved access to Hotline 1.5 and 1.7 servers
• Increased numeric length to 4 in file name ranges
• Removed unnecessary debug code resulting in an approx binary size reduction of 450k
• Changed the text string tables to improve load times
• Added AutoPurge Queue facility to purge the queue approx every 10 minutes
• Added "Get List" facility to download files in a remote URL list
• Added function to close program if pirate serial number is detected
• Fixed bug where Applescript "GetURL" did not function correctly
• Added "GetList" Applescript command
• Removed interactive messageboxes when processing via script.
• Fixed bug where port was incorrectly parsed on redirect.
1.5 Future Possibilities
1. More extensive download management functions.
99. Ideas needed!!
2. INSTALLATION
2.1 Requirements
1. A PPC Mac.
2. 8mb free RAM.
3. Open Transport.
4. About 3mb of disk space.
5. An Internet connection.
6. A screen set to 800x600 minimum.
2.2 Software Installation
1. Unstuff the distribution file - but you did that or you wouldn't be reading this!
2. Read this document thoroughly please.
3. Read the note about Virtual Memory ( Section 6.2 ).
4. You may now run MONICA.
5. If you wish to change the default preferences then click the "Prefs" button in the main window ( see Section 3.5 for more information ).
6. Included in the Monica distribution are two Helper applications that can facilitate your use of Monica. Please note that these are still in development and are therefore to be regarded as "Bonus" programs. ( See the file Readme_Helpers ).
2.3 Quick Start
1. When MONICA starts you are presented with the main control window. You may add new downloads to the queue by dropping URLs dragged from your browser onto the main window, or by pasting a URL onto the "Paste/Drop URL here" field. The URL must be a file URL e.g. "ftp://ftp.is.co.za/pub/rfc/rfc1000.txt" ( leave out the quotes ). It may be an ftp or a http URL.
INFO: If you have a number of URLs listed in a text file, you may paste multiple URLs in one go.
INFO: You may also manually add URLs by pressing the "Add" button ( see Section 3.1).
INFO: Some web links do not drag the correct file URL. This is a problem with the page HTML.
2. Make sure you are connected to the Internet.
3. You are now ready to start downloading. This you may do in one of two modes - Manual or Queued.
4. Manual Downloading. This is useful when you want to control the download starts by yourself. To start a download, highlight a queued item then press the "Get It Now!!" button.
INFO: You cannot not start more that 4 simultaneous downloads in this fashion.
5. Queued Downloading. This is where to downloading power of MONICA begins to show itself! Press the "Start Queue" button and wait a few seconds. The items in the queue will automatically start downloading.
INFO: By default MONICA allows 2 simultaneous downloads. You may set this to between 1 and 4 in the Prefs function ( see Section 3.5 ).
6. MONICA will automatically restart downloads where the server stops the download before it is complete. MONICA will also attempt to resume the download in such cases.
INFO: Note that by default MONICA stores downloads in a folder called "Downloads". You may change this in the preferences ( see Section 3.5 ).
INFO: Note that not all http/ftp servers support resuming. If not, MONICA will start at the beginning.
7. MONICA attempts to set the MAC Type and Creator values for downloaded files based upon the file extensions. This is done via a list that is user-maintainable.
8. When you have finished your session press the "Quit" button or close the main window.
3. COMMANDS AND SETTINGS
3.1 What are all these buttons?
1. Add.
Pressing this will open a window in which you can manually add a new URL.
The "Port" field is normally automatically set for you, but you may override it if you know the server port is non-standard.
The "Login" and "Password" fields are again automatically set but may be overwritten. This provides your login information to ftp and Hotline servers, and is only relevant to http URLs that require authorisation.
If you wish MONICA to automatically resume a download from a previous session then check the "Try to Restart" checkbox. If this is NOT checked, and a file with the same name exists in your Downloads folder, that file will be deleted. Once MONICA is running she will ALWAYS try to resume after the first attempt goes wrong.
The "Timeout" field specifies the number of seconds to wait without receiving any data before restarting the download.
The "Times to Retry" field specifies the number of times to keep on trying if errors occur. This does NOT apply to errors such as "File not found" or "Invalid password", as in such cases trying to restart is a bit pointless.
The "Local Folder" field and "Select" button allow you to choose where the file is to be put on your computer.
The "Local Name" field allows you to choose the local name of the downloaded file.
2. Edit.
You may change details about a download if it is not currently in progress or actively queued by highlighting it on the queue list and pressing this button.
You may also edit downloads by double-clicking on them in the queue list.
3. Delete.
You may delete a queued download if it is not currently in progress by highlighting it on the queue list and pressing this button.
You may also just press the "del" key after highlighting the download in the queue. You may use the cursor up and down arrows in the queue list to navigate.
4. Enable.
You may re-activate a download previously put on hold by highlighting it on the queue list and pressing this button. You may also re-activate downloads that had errors, or were successfully completed, in this way.
5. Hold.
You may de-activate a download by highlighting it on the queue list and pressing this button. This effectively puts the download on hold and it is ignored by the queue until re-activated.
6. Prefs.
Pressing this button allows you to enter various default parameters. These parameters apply by default to any new downloads added to the queue. Please see the "Preferences" section below ( Section 3.5 ).
7. Types.
Pressing this button allows you to enter parameters for setting the Mac file Type and Creator properties of downloaded files based upon file extensions ( the letters after the last "." in the file name ). You may add new ones or delete any existing parameters in this window. Setting these up correctly for your machine will allow you to double-click on downloaded files to open them with your chosen application.
8. Times.
Pressing this button allows you to maintain queue schedule times i.e.: to set times at which to start or stop the queue. For example, if you wish your college/work computer to start downloads after hours, you may set the queue to start at a later time. You may also set it to stop at a specified time, to start PPP or stop it at a later time.
INFO: Note that MONICA must be running at the time for these schedule functions to work.
INFO: Note that the schedule is SELF-PURGING and any items referring to past times are automatically deleted ( 10 minute safety zone ).
You may add a start or stop parameter by setting the date and time and then pressing the "Add" button. To delete an item, highlight it and press the "Delete" button. You may cancel any changes made by using the "Cancel" button, or save the changes to the schedule using the "Save" button. Starting and stopping the queue by means of schedule items is accurate to within a minute. You may not add more than one event for the same time.
9. Purge
This will purge the queue of all queue items that have been successfully downloaded. It will not purge items that have had errors.
10. Start Queue / Stop Queue.
This toggle button starts and stops the queue function.
Starting the queue causes MONICA to cycle through the queue list and start downloading any items in a queued status when a download slot becomes available. The queue is checked every 8-10 seconds - so be a little patient!
Stopping the queue does NOT abort any running downloads, but prevents any new ones starting.
11. Show/Hide.
This toggle button will show or hide a small window onto which you can drop URLs. Often, when browsing, you have very little screen space available, and this allows you to place a small window on a visible part of the screen so that it is not necessary to bring Monica to the front on your screen. You should move this to some convenient place on your screen.
12. Export.
This button allows you to export your queue as a list of URLs into a text file.
13 Helper Apps.
This brings up a new small window from which you can start any available Monica Helper Applications.
14. HTTP/FTP/Hotline slot indicator buttons.
These indicate the number of ftp, http, and Hotline downloads currently in progress. The indicators change colour when a download slot is active, and clicking on an active button will bring that download window to the front.
15. Save Queue.
MONICA automatically saves the queue every 10 minutes or so. This button allows you to save the queue immediately. Use it if you have just spent 10 minutes loading up a complicated set of URLs!
16 Queued.
This indicates the number of items in the queue in a "Queued" status ( ie: awaiting download ).
17 Get List.
MONICA has a facility to download off the net a list of files for further downloading. The URL for this list may be entered in the Preferences under the "Transmission" tab in the "Base URL" field ( see Section 3.5 ). The file pointed to by this URL must be a standard text file with a single URL per line eg:
http://www.someplace.com/file1.zip
ftp://ftp.anotherplace.com/file2.hqx
Pressing this "Get List" button will cause MONICA to:
• Delete any pre-existing ( old ) list.
• Download the list from the Base URL.
• Load all URLs in the list file into the queue.
• Start the queue.
• Download the files.
• Stop the queue.
• Purge the queue.
This facility allows you to set up a list of downloads on a remote computer and the get MONICA to download all the files in the list.
3.2 The Queue Display
MONICA keeps you informed of status and progress by means of status text and pseudo-LEDs in the main window.
The colour codes are shown towards the bottom of the main window.
Looking at a queued item from left to right, the information is as follows:
Pseudo-LED.
"Queued" means the item is waiting in the queue.
"Starting" means the download is starting.
"On Hold" means that this item is on hold and is being ignored by the queue.
"In Process" means that MONICA has connected to the remote server and the download
is about to start.
"Error" means that an error occurred. A brief description is displayed.
"Received" means that the file was successfully received.
"Blocked" means that you have added a new item to the queue with the same name as another
item in the queue or as an existing file in your Downloads folder. To download such a file
you need to edit it so as to resolve this conflict.
URL.
This is the URL!
Retries.
This is the number of times MONICA has tried to get the file.
Size.
This is the file size if the server gave it.
Information.
This is verbal information about the download status. See below.
3.3 Status Information
Received:
The file has been successfully received.
Files Same Size
The remote file is precisely the same size as the local file so it was not downloaded again.
Check Size
From all the information received by MONICA from the remote server the file has been successfully downloaded, but the local file size is different to the size anticipated, or the remote server did not tell MONICA the size. Possible file corruption, or an incomplete download, but probably downloaded ok.
Local File Bigger
From all the information received by MONICA from the remote server the file has been successfully downloaded, but the local file size is bigger than anticipated. Possible file corruption.
Local File Exists
The local file is the same size as the remote file so it was not downloaded again.
User Abort
You pressed the big ABORT! button.
Internal Error
This is an internal MONICA problem. Please notify me of what happened.
Bad Password
Your login/password were not accepted.
Bad Login
Your login/password were not accepted.
File not Found
The remote file was not found.
Over Retry Limit
MONICA has tried the download unsuccessfully the number of times you specified.
OT Not Installed
MONICA requires Open Transport. You don't have it installed and working.
Domain Not Found
The remote site cannot be found. Either it doesn't exist, or your DNS server is having a bad day.
Redirected html
The http server has said that the required file has been moved, but links to a html page. Many servers redirect a "File Not Found" to another web ( html) page so as to tell you in glorious technicolor that the file cannot be found. MONICA ignores redirections to html pages for this reason.
Not Allowed
The Hotline server you are trying to download from does not let your login download files.
File Missing
The file you are attempting to download has been removed from the server location.
In Drop Box
The file you are trying to get from a Hotline server is in a Drop Box and is thus not available to you.
Download Error
There is an unknown problem trying to get a file from a Hotline server.
Disk Error
There has been an error writing to disk.
Misc OT Error
Open Transport has returned one of its many incomprehensible errors.
Error nnn
Some other error occurred. Please tell me if you get these frequently.
3.4 Download sub-windows
When a download is in progress a sub window appears that shows what is going on.
Each sub-window has a big "Abort!" button that you may press to abort the download.
There is also a "Diagnose/Ignore" toggle button. This will cause MONICA to put up a window when the download attempt is over showing the MONICA-server dialogue. Use it when you are not sure why you cannot download a file, but the dialogue in the download sub-window whizzes by too fast. Switch off the option by pressing the button again.
The window also shows the following:
URL:
The URL
Total in:
The total bytes that are currently written to disk, including anything received on prior attempts.
File Size:
If the remote server told MONICA the file size, it is displayed here.
Restart at:
The number of bytes received prior to this download attempt.
BPS:
Download speed in bytes per second, calculated as the total bytes received this attempt divided by the elapsed seconds since starting this attempt.
Server Dialog Display:
This shows the dialog between MONICA and the remote server. Lines beginning with a "*" are informational lines generated by MONICA. Lines beginning ">" are outgoing commands. Lines starting "<" are responses from the remote server.
Progress Bar:
Progress! Only useful if the remote server told MONICA the file size.
Time Left:
Estimate of the time left on the download based upon the BPS rate.
Expected:
The length of the complete transmission expected from a Hotline server.
Received:
How much of the transmission has been received from a Hotline server.
3.5 Preferences
GENERAL
The "Suppress Sounds" checkbox allows you to make MONICA run silently.
The "Comment Files" checkbox allows you to make MONICA place the file URL in the file's comment field after downloading.
The "Translate Hex values" checkbox, if checked, will translate hexadecimal values in dropped URLs. For example in the URL "ftp://ftp.somewhere.com/files/abcd%20efg.zip" the "%20" represents a space character. Some browsers embed the hexadecimal values of certain characters when allowing you to drag a URL. In this example the "%20" would be translated to a space character. If the checkbox is left unchecked no translation takes place.
The "Autostart Queue" specifies that MONICA should automatically start the queue when the program starts up.
The "AutoPurge Queue" specifies that MONICA should automatically purge the queue approximately every 10 minutes.
The "Download Folder" field and "Select" button allow you to specify where MONICA should put the downloaded files.
TRANSMISSION
The "Retry Delay" parameter specifies how many seconds MONICA must wait before trying a download again. Some servers get annoyed if you reconnect too quickly, and you can get around this by setting this parameter.
The "Number of Retries" specifies the number of times to retry a download if errors occur.
The "Timeout" field specifies the number of seconds to wait without receiving any data before restarting downloads.
The "Max Downloads" specifies the maximum number of downloads that can run simultaneously in queued download mode.
The Base URL field allows you to specify a remote file URL that points to a file containing a further list of files for download. ( For operation of this feature see Section 3.1 subsection 17 ).
HTTP
The "HTTP Proxy Server" field allows you to enter a HTTP proxy server name if you use one. If you do not wish to use a proxy server then leave this field blank. See the section on Proxy Servers ( Section 3.7 ).
The "Proxy Port" field should contain the appropriate port number to use to connect to your proxy server if you use one.
The "Ignore Chunked Error" checkbox allows you to control how MONICA treats chunked mode transfers. If you are happy with how MONICA deals with these, check the box.
The "Referer" field contains the text that is sent to the remote server to tell it which web page sent you to this URL. Several servers check to see if that is them, and if not they will disallow the download. If you leave this blank then the server you are downloading from is used.
The "User Agent" field tells the remote server what client program you are running. You know you are running MONICA, but sometimes its a good idea to tell the remote server that you are one of the main browsers. The description "Mozilla/4.04 (Macintosh; I; PPC, Nav)" is from Netscape 4.04 for Mac.
FTP
The "User name" should be left as "anonymous" for ftp access in most cases.
The "Login" should be your email address.
The "Use Passive FTP" checkbox allows you to specify globally whether FTP transfers should take place in "passive" mode. "Passive" mode lets the remote server specify the data transfer port, as opposed to normal mode where the client ( MONICA ) specifies the port. Some FTP servers only allow passive downloads, others disallow passive downloads. Try checking this option if you are having problems transferring via FTP.
HOTLINE
In the "Nickname" field enter your chosen Hotline nickname.
In the "Icon Number" field put the number of the icon you like using in Hotline.
PPP
Check the "Start PPP on Program Start" box if you want MONICA to fire up PPP when she loads.
Check the "Stop PPP on Queue Completion" box if you want MONICA to stop PPP when there are no more items to download in the queue.
Check the "Stop PPP on Program Quit" box if you want MONICA to stop PPP when she quits.
Note: Please see the section on MONICA and PPP ( Section 5.3 ).
REGISTER
If you have paid, please enter your name ( EXACTLY as it was submitted to Kagi and stated in our registration email to you ), and the registration code you have received. It would be best to copy and paste these from the email you received notifying you of your registration code. Note that both fields are case-sensitive. Then press the "Register" button to save your registration details. Once your registration code has been accepted by the program you do not need to enter it again.
3.6 File Name Ranges
If you wish to load a group of URLs for files with name ranges ( eg file01.zip, file02.zip etc), you may do so by Pasting a SINGLE URL in the format "http://www.somewhere.com/file[01-22].zip" into the Paste/Drop URL here box. It will NOT work with the Drag-and-Drop function, nor with the Add button function. For this feature to work please do not paste multiple URLs on multiple lines in one go. Pasting a URL like this will generate the appropriate numer of queue items.
Permissible ranges are in the formats [a-z], [A-Z], [0-9], [00-99]. You may not use a format such as [8-11] - both start and end parameters must be the same length, and not more than two characters long.
3.7 Proxy Servers
MONICA allows the use of simple proxy servers for HTTP downloads. The only type of proxy server catered for at this stage is the type that does not require any user name or password details. If a server name is entered in the HTTP Proxy Server field in the Preferences, MONICA will attempt to route HTTP requests to that server. If the field is left blank MONICA will not use a proxy server.
If you have to use a Proxy Server to access the Net, you should normally also set FTP transfers to Passive Mode in the Preferences.
CAUTION!!
The mechanics of a HTTP Proxy involve connecting to the Proxy, which in turn connects to the remote server. In my experience some Proxy Servers are NOT as tolerant of HTTP funnies as MONICA is, with the result that, where MONICA will download a file fine, the Proxy server will not. If you can access the Net without a Proxy and you get a lot of "400 Cache detected error" messages on downloads when using the Proxy, then try without using the Proxy. This error is often caused by the Proxy Server not being able to cope with the HTTP funnies of the remote server, and is most likely NOT MONICA's fault! Please also see the "Funnies" section of this document ( Section 6.4 ).
INFO: There is a list of publicly accessible proxies at http://cool.icestorm.com/proxys/.
